LwM2M Advanced Firmware Update

Draft Version: x.y.z - yyyy-mm-dd

Open Mobile Alliance

OMA-TS-[FunctionalName]-Vx_y_z-yyyymmdd-D

main: 14 Jun 2022 15:38:00 rev: 7a98586

Unless this document is clearly designated as an approved specification, this document is a work in process, is not an approved Open Mobile Alliance™ specification, and is subject to revision or removal without notice.

You may use this document or any part of the document for internal or educational purposes only, provided you do not modify, edit or take out of context the information in this document in any manner. Information contained in this document may be used, at your sole risk, for any purposes. You may not use this document in any other manner without the prior written permission of the Open Mobile Alliance. The Open Mobile Alliance authorizes you to copy this document, provided that you retain all copyright and other proprietary notices contained in the original materials on any copies of the materials and that you comply strictly with these terms. This copyright permission does not constitute an endorsement of the products or services. The Open Mobile Alliance assumes no responsibility for errors or omissions in this document.

Each Open Mobile Alliance member has agreed to use reasonable endeavors to inform the Open Mobile Alliance in a timely manner of Essential IPR as it becomes aware that the Essential IPR is related to the prepared or published specification.
However, the members do not have an obligation to conduct IPR searches. The declared Essential IPR is publicly available to members and non-members of the Open Mobile Alliance and may be found on the “OMA IPR Declarations” list at https://www.omaspecworks.org/about/intellectual-property-rights/. The Open Mobile Alliance has not conducted an independent IPR review of this document and the information contained herein, and makes no representations or warranties regarding third party IPR, including without limitation patents, copyrights or trade secret rights. This document may contain inventions for which you must obtain licenses from third parties before making, using or selling the inventions. Defined terms above are set forth in the schedule to the Open Mobile Alliance Application Form.

NO REPRESENTATIONS OR WARRANTIES (WHETHER EXPRESS OR IMPLIED) ARE MADE BY THE OPEN MOBILE ALLIANCE OR ANY OPEN MOBILE ALLIANCE MEMBER OR ITS AFFILIATES REGARDING ANY OF THE IPR’S REPRESENTED ON THE “OMA IPR DECLARATIONS” LIST, INCLUDING, BUT NOT LIMITED TO THE ACCURACY, COMPLETENESS, VALIDITY OR RELEVANCE OF THE INFORMATION OR WHETHER OR NOT SUCH RIGHTS ARE ESSENTIAL OR NON-ESSENTIAL.

THE OPEN MOBILE ALLIANCE IS NOT LIABLE FOR AND HEREBY DISCLAIMS ANY DIRECT, INDIRECT, PUNITIVE, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES ARISING OUT OF OR IN CONNECTION WITH THE USE OF DOCUMENTS AND THE INFORMATION CONTAINED IN THE DOCUMENTS.

THIS DOCUMENT IS PROVIDED ON AN "AS IS" "AS AVAILABLE" AND "WITH ALL FAULTS" BASIS.

Copyright 2024 Open Mobile Alliance.

Used with the permission of the Open Mobile Alliance under the terms set forth above.

1. Scope

This document defines the technical specification for an Advanced Firmware Update Object, to be used in conjunction with the Lightweight M2M enabler.

2. Reference

- Gating Criteria requirement
- https://wiki.openmobilealliance.org/pages/viewpage.action?pageId=38634506#GatingCriteria(GC)-References

2.1. Normative References

The policy for reference lists is:
1.  OMA documents listed should have at least one approved version – draft-only docs should not be referenced.
Exception exists for documents that will be approved with or after the referenced doc is approved (may be
part of same enabler package).  In short – approved docs should not reference unapproved docs.
2.  When a reference is made to an OMA specification, then Open Mobile Alliance with the TM symbol (™) should
be used in the description.
3.  The name + version (no date) for OMA specifications are generally sufficient – dates should be used only
if there is a specific reason to limit the usage.
4.  For references to WAP Forum docs, dates should not be included as DID's for the old WAP Forum specifications
are enough and the reference description should refer to WAP Forum™.
5.  References to other affiliate docs should similarly provide sufficient information to uniquely determine the
needed document and should provide the appropriate source information.
6.  The URL for OMA material (new OMA and affiliate) should always be http://www.openmobilealliance.org (an
exception is OMNA that is reached through http://www.openmobilealliance.org/tech/omna)

Models to use
    [REFLABEL]  <General Model> "Ref Title", Ref information (source, date, id), URL:http//<ref-source>/
    [OMADOC]    <OMA Model> "OMA Document Title",{ Version x.y,} Open Mobile Alliance™, OMA <docname>{ <version>},
                URL:http//www.openmobilealliance.org/

If there are no entries in the table – enter ‘none’ to be clear.

DELETE THIS COMMENT

Add/Remove reference rows as needed - DELETE This Row

2.2. Informative References

Check the version of the Dictionary you are using and update the reference below.  Delete the [OMADICT] entry if
the dictionary is not used.  In general, use the latest available version unless seeking alignment with an
existing set of specifications.

DELETE THIS COMMENT

Add/Remove references as needed - DELETE This Row

3. Terminology and Conventions

- Gating Criteria requirement
- https://wiki.openmobilealliance.org/pages/viewpage.action?pageId=38634506#GatingCriteria(GC)-Terminology&Conventions

3.1. Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

All sections and appendixes, except "Scope" and "Introduction", are normative, unless they are explicitly indicated to be informative.

If needed, describe or declare using appropriate normative references the additional conventions that are used.  DELETE THIS COMMENT

3.2. Definitions

Add definitions in new rows of the following table as needed.  The following examples show how dictionary references should be made
as well as locally defined terms.  This table should be maintained in sorted alphabetic order based on the labels of the terms.

Examples:
    Entity              Use definition #1 from [OMADICT]
    Interactive Service Use definition from [OMADICT]
    Local Term          The definition description would be presented directly

DELETE THIS COMMENT

Add/Remove definition rows as needed - DELETE This Row

Kindly consult [OMADICT] for more definitions used in this document.

3.3. Abbreviations

Add abbreviations as needed.  No special notation should be made regarding terms copied from the Dictionary.
The list should be maintained in alphabetic order. DELETE This Row

4. Introduction

From a market perspective...
  o What can you do with this specification?
  o What problem does this solve?
  o How can this specification be applied?
  o Consider the target audience and provide deployment examples as possible.
DELETE THIS COMMENT

4.1. Version 1.0

This section provides a high level, concise and informative description of the main functionality supported in
the initial version of the specification.  The description should be brief, target length should be a few paragraphs.
When the enabler or reference release is finished, this description should be aligned with the final functionality.

DELETE THIS COMMENT

4.2. Version (x.y)

This section should be included for each new major or minor version of the specification.

It should provide a high level, concise and informative description of the new or modified functionality introduced
in this version of the specification, compared to the previous version.  The description should be brief, target
length should be a few paragraphs.  When the enabler or reference release is finished, this description should be
aligned with the final functionality differences.

DELETE THIS COMMENT

4.2.1. Version (x.y.z)

This section should be included for each new service release of the specification.   It should describe at a high
level the main changes made to the specification compared to the previous version.  The description should be brief,
target length should be one paragraph.

DELETE THIS COMMENT

5. LwM2M Object: Firmware Update

Description

Object definition

Resource definitions

5.1. Firmware Update State Machine

Figure: 5.1.0.1.-1 Firmware Update Mechanisms shows a possible implementation of the firmware update mechanism, described as a UML 2.0 state diagram. The state diagram consists of states, drawn as rounded rectangles, and transitions, drawn as arrows connecting the states. The syntax of the transition is trigger [guard] / behaviour. A trigger is an event that may cause a transition, guard is a condition and behaviour is an activity that executes while the transition takes place. The states additionally contain a compartment that includes assertions and variable assignments. For example, the assertion in the IDLE state indicates the value of the “Update Result” resource (abbreviated as “Res”) must be between 0 and 11. The State resource is set to zero (0) when the program is in this IDLE state.

Any operation to the Firmware Update Object that would result in undefined behavior because that specific operation is not identified as a trigger in the state machine (e.g. Write to Package URI while in DOWNLOADING state) SHOULD be rejected.

Errors during the Firmware Update process MUST be reported only by the “Update Result” resource. For instance, when the LwM2M Server performs a Write operation on resource “Package URI”, the LwM2M Client returns a Success or Failure for the Write operation. Then if the URI is invalid, it changes its “Update Result” resource value to 7.

5.1.0.1. TODO: Update the state machine diagram

Intended changes:

• Assertions reading “Res<=11” shall be changed to “Res<=13”
• Additional state transition from the DOWNLOADING to IDLE state shall be added: “Conflicting state [Res==12]”
• Additional state transition from the UPDATING to IDLE state shall be added: “Dependency error [Res==13]”

5.2. Examples

5.2.1. General update flow

The example depicted in Figure: 5.2.1.-1 Example of a LwM2M Server pushing a firmware image to a LwM2M client illustrates a successful message exchange where a LwM2M Server pushes a firmware image to a LwM2M Client using the block-wise transfer. In this example the LwM2M Server indicates a block size of 128 bytes and the firmware image of 80 KiB (=81920 bytes) will be sent to the LwM2M Client in 640 messages with each 128 bytes payload. Since the LwM2M Server-provided block size matches the preferences of the LwM2M Client the exchange proceeds until the full firmware image is downloaded. In this example, no messages are lost during transmission.

The second example shown in Figure: 5.2.1.-2 Example of a client fetching a firmware image illustrates the case where the client was provided with a URI by the LwM2M Server (using the Package URI resource) and therefore fetches the firmware image from the indicated server. Note that only the retrieval of the firmware image from the LwM2M Server is shown in Figure: 5.2.1.-2 Example of a client fetching a firmware image and not the initial configuration of the Package URI.

5.2.2. Example client data modle - initial state

5.2.2.1. Lwm2M Firmware update Object – Application partition [/5/0]

This partition governs the image for the main application firmware that implements the core device functionality.

5.2.2.2. Lwm2M Firmware update Object – Trusted firmware partition [/5/1]

This partition governs the image for the main application firmware that implements the core device functionality.

5.2.2.3. Lwm2M Firmware update Object – Bootloader [/5/2]

This partition governs the image for the main application firmware that implements the core device functionality.

5.2.2.4. Lwm2M Firmware update Object – Modem [/5/3]

This partition governs the image for the main application firmware that implements the core device functionality.

5.2.3. Example upgrade scenarios

5.2.3.1. Version conflict

Let’s assume that the Application firmware version 2.0 requires the TEE firmware to also be updated to version 2.0 or later.

1. The LwM2M Server writes "http://example.com/app_2.0.bin" to resource /5/0/1 (Package URI of the Application partition)
2. The instance enters the Downloading state, downloads the image, and enters the Downloaded state
3. Resource /5/0/17 (Conflicting instances) changes value to: [0] = 5:1; this informs the server that instance /5/1 requires attention due to dependency conflict
4. If the server nevertheless issues Execute on /5/0/2, the device immediately reverts back to the Downloaded state, with Update Result set to 13 (Dependency error)
5. The LwM2M Server then writes "http://example.com/tee_2.0.bin" to resource /5/1/1 (Package URI of the TEE partition)
6. The instance enters the Downloading state, downloads the image, and enters the Downloaded state
7. Resource /5/0/17 (Conflicting instances) changes value back to empty.
8. Resource /5/0/16 (Linked instances) changes value to: [0] = 5:1; resource /5/1/16 (Linked instances) changes value to: [0] = 5:0; this signifies that by default, the device will upgrade both when the Update operation is executed on either of the instances
9. The LwM2M Server issues Execute on /5/0/2
10. The device enters Updating state, performs update of both partitions, reboots, and reconnects to the server
11. The State on both /5/0 and /5/1 instances read 0 (idle), Update Result on both is 1 (success), and the version numbers have been updated so that /5/0/15 = 2.0 and /5/0/16 = 2.0

5.2.3.2. Multi-partition image

1. The LwM2M Server writes "http://example.com/app_tee_2.1.zip" to /5/0/1 (Package URI of the Application partition)
2. Instance 0 enters the Downloading state, downloads the image, and the device logic detects that the file contains images for both the Application and TEE partitions
3. Both instance 0 and instance 1 enter the Downloaded state

5.2.3.3. Conflicting downloads

1. The LwM2M Server writes "http://example.com/tee_2.0.bin" to /5/1/1 (Package URI of the TEE partition)
2. Instance 1 enters the Downloading state, downloads the image, and enters the Downloaded state
3. The LwM2M Server writes "http://example.com/app_tee_2.1.zip" to /5/0/1 (Package URI of the Application partition)
4. Instance 0 enters the Downloading state, downloads at least some part of the image, and then the device logic detects that the file contains images for both the Application and TEE partitions
5. The device aborts the download; instance 0 reverts to the Idle state, with Update Result set to 12 (Conflicting state); instance 1 remains in the Downloaded state, with the 2.0 image in memory.
6. Resource /5/0/17 changes value to: [0] = 5:1; this serves as the detail for the “Conflicting state” error, informing on which instances were conflicting

5.2.3.4. Implicit and explicit linked updates

1. The LwM2M server writes the following values:

   a. "http://example.com/app_2.0.bin" to resource /5/0/1 (Package URI of the Application partition) b. "http://example.com/tee_2.0.bin" to resource /5/1/1 (Package URI of the TEE partition) c. "http://example.com/boot_2.2.bin" to resource /5/2/1 (Package URI of the Bootloader partition) d. "http://example.com/modem_22.02.bin" to resource /5/3/1 (Package URI of the Modem partition)

2. The device downloads the images, eventually all the instances enter the Downloaded state

3. Resource /5/0/16 (Linked instances) changes value to: [0] = 5:1; resource /5/1/16 (Linked instances) changes value to: [0] = 5:0; this signifies that by default, the device will upgrade instances 0 and 1 in one go when the Update operation is executed on either of them

4. Either of the sub-scenarios described below follows

5.2.3.5. Implicit linked update

1. The LwM2M server issues Execute with no arguments on /5/0/2 or /5/1/2
2. The device enters Updating state, performs update of the Application and TEE partitions, reboots, and reconnects to the server
3. The State on both /5/0 and /5/1 instances read 0 (idle), Update Result on both is 1 (success), and the version numbers have been updated
4. Instances /5/2 and /5/3 remain in the Downloaded state if possible

5.2.3.6. Explicit linked update

1. The LwM2M server issues Execute on /5/0/2 with argument payload: "0='</5/1>,</5/2>,</5/3>'"
2. The device enters Updating state, performs update of all four partitions, reboots, and reconnects to the server
3. The State on all instances read 0 (idle), Update Result on all of them is 1 (success), and the version numbers have been updated

5.2.3.6.1. Explicit single partition update

1. The LwM2M server issues Execute on /5/1/2 with argument payload: “0”
2. Instance 1 enters Updating state, the device performs update of only the TEE partition (ignoring the Linked Instances), and reconnects to the server
3. The State on instance /5/1 reads 0 (idle), corresponding Update Result is 1 (success), and the version number has been updated
4. Instances /5/0, /5/2 and /5/3 remain in the Downloaded state if possible

5.2.3.6.2. Explicit single partition update – unsuccessful

1. The LwM2M server issues Execute on /5/0/2 with argument payload: “0”
2. Instance 0 immediately reverts back to the Downloaded state, with Update Result set to 13 (Dependency error), because application version 2.0 requires the TEE partition to be updated to version 2.0 first or at the same time
3. Resource /5/0/17 changes value to: [0] = 5:1; this serves as the detail for the “Dependency error” result, informing on which instances were conflicting

5.3. Firmware Update Consideration

If some Objects are not supported after firmware update, the LwM2M Client MUST delete all Object Instances of the Objects that are not supported.

Appendix A. Change History (Informative)

- Gating Criteria 
- https://wiki.openmobilealliance.org/pages/viewpage.action?pageId=38634506#GatingCriteria(GC)-DocumentHistory

A.1 Approved Version History

Appendix B. Static Conformance Requirements (Informative)

The notation used in this appendix is specified in [SCRRULES].Add link

The following is an optional model of a set of SCR tables.  DELETE THIS COMMENT

B.1 SCR for XYZ Client

B.2 SCR for XYZ Server